/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef C_INCLUDE_DRAWING_TEXT_RUN_H
#define C_INCLUDE_DRAWING_TEXT_RUN_H

/**
 * @addtogroup Drawing
 * @{
 *
 * @brief Provides the functions for 2D graphics rendering, text drawing, and image display.
 * This module uses the physical pixel unit, px.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 *
 * @since 8
 * @version 1.0
 */

/**
 * @file drawing_text_run.h
 *
 * @brief Declares the capabilities of runs, such as obtaining the typographic boundary and drawing.
 * File to include: "native_drawing/drawing_text_run.h"
 * @library libnative_drawing.so
 * @since 14
 * @version 1.0
 */

#include "drawing_text_declaration.h"
#include "drawing_types.h"

#ifdef __cplusplus
extern "C" {
#endif
/**
 * @brief Obtains an array of character indices for glyphs within a specified range of a run,
 * where the indices are offsets relative to the entire paragraph.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @param start Start position in the run. If a negative number is passed, a null pointer is returned.
 * @param length Length of the range in the run. If the length is 0, all character indexes of the run are obtained.
 * If the length is less than 0, a null pointer is returned.
 * @return Returns the character index array.
 * @since 14
 * @version 1.0
 */
OH_Drawing_Array* OH_Drawing_GetRunStringIndices(OH_Drawing_Run* run, int64_t start, int64_t length);

/**
 * @brief Obtains character indices of glyphs in a run by index.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param stringIndices Pointer to a character index array.
 * @param index Index in the character index array.
 * @return Returns the character indices.
 * @since 14
 * @version 1.0
 */
uint64_t OH_Drawing_GetRunStringIndicesByIndex(OH_Drawing_Array* stringIndices, size_t index);

/**
 * @brief Releases the pointer to a character index array object.
 * 
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param stringIndices Pointer to a character index array.
 * @since 14
 * @version 1.0
 */
void OH_Drawing_DestroyRunStringIndices(OH_Drawing_Array* stringIndices);

/**
 * @brief Obtains the range of glyphs generated by a run.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @param location Start position of the range in the run, which is an offset relative to the entire paragraph.
 * @param length Length of the range.
 * @since 14
 * @version 1.0
 */
void OH_Drawing_GetRunStringRange(OH_Drawing_Run* run, uint64_t* location, uint64_t* length);

/**
 * @brief Obtains the typographic boundary of a run.
 * The typographic boundary is related to the font and font size used for typography,
 * but not the characters within the text.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @param ascent Distance from the top of the tallest character to the baseline in the run.
 * @param descent Distance from the bottom of the lowest character to the baseline in the run.
 * @param leading Vertical space between lines in the run.
 * @return Returns the layout width of the run.
 * @since 14
 * @version 1.0
 */
float OH_Drawing_GetRunTypographicBounds(OH_Drawing_Run* run, float* ascent, float* descent, float* leading);

/**
 * @brief Paints the text contained in a run on the canvas.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param canvas Pointer to an {@link OH_Drawing_Canvas} object.
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @param x X coordinate of the run.
 * @param y Y coordinate of the run.
 * @since 14
 * @version 1.0
 */
void OH_Drawing_RunPaint(OH_Drawing_Canvas* canvas, OH_Drawing_Run* run, double x, double y);

/**
 * @brief Obtains the image boundary of a run.
 * The image boundary is related to characters and is equivalent to the visual boundary.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @return Returns the pointer to an {@link OH_Drawing_Rect} object, which describes the image boundary of the run.
 * @since 14
 * @version 1.0
 */
OH_Drawing_Rect* OH_Drawing_GetRunImageBounds(OH_Drawing_Run* run);

/**
 * @brief Releases the pointer to an image boundary object of a run.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param rect Pointer to the image boundary, which is an {@link OH_Drawing_Rect} object.
 * @since 14
 * @version 1.0
 */
void OH_Drawing_DestroyRunImageBounds(OH_Drawing_Rect* rect);

/**
 * @brief Obtains an array of glyphs within the specified range of a run.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @param start Start position in the run. If a negative number is passed, a null pointer is returned.
 * @param length Length of the range in the run.
 * If the length is 0, all character indexes of the run are obtained.
 * If the length is less than 0, a null pointer is returned.
 * @return Returns the pointer to an {@link OH_Drawing_Array} object, which holds the glyphs.
 * @since 14
 * @version 1.0
 */
OH_Drawing_Array* OH_Drawing_GetRunGlyphs(OH_Drawing_Run* run, int64_t start, int64_t length);

/**
 * @brief Obtains individual glyphs in a run by index.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param glyphs Pointer to the glyph array, which is an {@link OH_Drawing_Array} object.
 * @param index Index in the glyph array.
 * @return Returns the individual glyphs.
 * @since 14
 * @version 1.0
 */
uint16_t OH_Drawing_GetRunGlyphsByIndex(OH_Drawing_Array* glyphs, size_t index);

/**
 * @brief Releases the pointer to a glyph array in a run.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param glyphs Pointer to the glyph array, which is an {@link OH_Drawing_Array} object.
 * @since 14
 * @version 1.0
 */
void OH_Drawing_DestroyRunGlyphs(OH_Drawing_Array* glyphs);

/**
 * @brief Obtains the positions of glyphs within the specified range of a run.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @param start Start position in the run. If a negative number is passed, a null pointer is returned.
 * @param length Length of the range in the run.
 * If the length is 0, all character indexes of the run are obtained.
 * If the length is less than 0, a null pointer is returned.
 * @return Returns the pointer to an {@link OH_Drawing_Array} object, which holds the glyph positions.
 * @since 14
 * @version 1.0
 */
OH_Drawing_Array* OH_Drawing_GetRunPositions(OH_Drawing_Run* run, int64_t start, int64_t length);

/**
 * @brief Obtains the positions of individual glyphs in a run by index.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param positions Pointer to the glyph position array, which is an {@link OH_Drawing_Array} object.
 * @param index Index of the glyph position array in the run.
 * @return Returns the pointer to an {@link OH_Drawing_Point} object,
 * which holds the positions of individual glyphs in the run.
 * @since 14
 * @version 1.0
 */
OH_Drawing_Point* OH_Drawing_GetRunPositionsByIndex(OH_Drawing_Array* positions, size_t index);

/**
 * @brief Releases the pointer to a glyph position array in a run.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param positions Pointer to the glyph position array, which is an {@link OH_Drawing_Array} object.
 * @since 14
 * @version 1.0
 */
void OH_Drawing_DestroyRunPositions(OH_Drawing_Array* positions);

/**
 * @brief Obtains the number of glyphs in a run.
 *
 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing
 * @param run Pointer to an {@link OH_Drawing_Run} object.
 * @return Returns the number of glyphs.
 * @since 14
 * @version 1.0
 */
uint32_t OH_Drawing_GetRunGlyphCount(OH_Drawing_Run* run);
#ifdef __cplusplus
}
#endif
/** @} */
#endif
